---
title: "Provided Overlays"
---

The grid shows overlays to communicate the grid's current state to the user. When data is loading or being exported and when there is no data or no rows match the current filter.


## Loading

{% metaTag tags=["showLoadingOverlay"] /%}

The loading overlay is displayed when the grid property `loading` is set to `true` and takes precedence over the other provided overlays.

{% apiDocumentation source="grid-options/properties.json" section="overlays" names=["loading"] /%}


## No Rows

When there are no rows the grid automatically displays the no-rows overlay. 


## No Matching Rows

The no-matching-rows overlay is displayed when the grid has rows but none of the rows match the current filter criteria. 


## Exporting

The exporting overlay is displayed when data is being exported from the grid to CSV or Excel.


## Example

The following example demonstrates all the provided overlays.

- Toggle the loading state to show/hide the loading overlay. 
- Note that the loading overlay takes precedence over the other provided overlays if they are shown at the same time.
- Clear the row data to show the no rows overlay.
- Set Non Matching Filter, sets row data and a non matching filter to show the no matching rows overlay.    
- Export the data to CSV

{% gridExampleRunner title="Provided Overlays" name="provided-overlays"  exampleHeight=300 /%}


## Customisation

The provided overlays can be customised to change their content or completely replaced with custom components. The grid still manages the timing of when the overlays are displayed based on grid state.

### Text Customisation

Customise the text within the provided overlays via the `overlayComponentParams` grid option using the `OverlayComponentUserParams` interface.

{% interfaceDocumentation interfaceName="OverlayComponentUserParams" /%}

```{% frameworkTransform=true %}
const gridOptions = {
    overlayComponentParams: {
        loading: { overlayText: 'Please wait while your data is loading...' },
        noRows: { overlayText: 'This grid has no data!' },
        noMatchingRows: { overlayText: 'Current Filter Matches No Rows' },
        exporting: { overlayText: 'Exporting your data...' },
    }
};
```

{% gridExampleRunner title="Provided Overlays Custom Text" name="provided-overlays-text"  exampleHeight=300 /%}

### Custom Overlay Components

{% if isFramework("javascript") %}
To provide a custom component for the provided overlays implement one of the following interfaces: `ILoadingOverlayComp`, `INoRowsOverlayComp`, `INoMatchingRowsOverlayComp` or `IExportingOverlayComp`.
{% /if %}

{% if isFramework("angular") %}
To provide a custom component for the provided overlays implement one of the following interfaces: `ILoadingOverlayAngularComp`, `INoRowsOverlayAngularComp`, `INoMatchingRowsOverlayAngularComp` or `IExportingOverlayAngularComp`.
{% /if %}

{% if isFramework("vue") %}
Any valid Vue component can be an overlay component, however it is also possible to implement the following optional methods:

{% interfaceDocumentation interfaceName="ILoadingOverlay" config={"asCode":true } /%}
{% /if %}
{% if isFramework("javascript", "angular") %}
Implement this interface to provide a custom overlay when data is being loaded.
{% /if %}


{% if isFramework("angular") %}
{% interfaceDocumentation interfaceName="ILoadingOverlayAngularComp" config={"asCode":true } /%}
The `INoRowsOverlayAngularComp`, `INoMatchingRowsOverlayAngularComp` or `IExportingOverlayAngularComp` interfaces follow a similar pattern to the `ILoadingOverlayAngularComp` above.

{% /if %}

{% if isFramework("javascript") %}
{% interfaceDocumentation interfaceName="ILoadingOverlayComp" config={"asCode":true } /%}

The `INoRowsOverlayComp`, `INoMatchingRowsOverlayComp` or `IExportingOverlayComp` interfaces follow a similar pattern to the `ILoadingOverlayComp` above.
{% /if %}


Then set the custom overlay to its matching key in the `components` map as described in [Overriding Grid Components](./components/#overriding-grid-components). Custom parameters can be supplied via the `overlayComponentParams` grid option.

```{% frameworkTransform=true %}
const gridOptions = {
    components: {
        agLoadingOverlay: CustomLoadingOverlay,
        agNoRowsOverlay: CustomNoRowsOverlay,
        agNoMatchingRowsOverlay: CustomNoMatchingRows,
        agExportingOverlay: CustomExportingOverlay
    },
};
```


### Overlay Component Selector

To dynamically override a provided overlay with a custom component implement the `overlayComponentSelector(params)` callback. The callback params include an `overlayType` property which identifies which of the provided overlays that grid wants to display. The return type should match the `OverlaySelectorResult` interface.

{% apiDocumentation source="grid-options/properties.json" section="overlays" names=["overlayComponentSelector"] /%}

Returning `undefined` from the selector will fall back to the overlay specified in `params.overlayType`.


```{% frameworkTransform=true %}
const gridOptions = {
    overlayComponentSelector: (params) => {
        if (params.overlayType === 'loading') {
            return {
                component: CustomLoadingOverlay,
                params: {
                    loadingMessage: 'Please wait while data is loading...'
                }
            };
        }
        // return undefined to use the provided overlay for other overlay types
        return undefined;
    },
};
```

In the example below the loading overlay is overridden via the `overlayComponentSelector` but the no rows overlay is not.

{% gridExampleRunner title="Overlay Component Selector" name="custom-overlay-selector"  exampleHeight=300 /%}


### Combined Overlay Component

Provide a custom component to `overlayComponent` to be used in place of all the provided overlays. The custom component receives a `overlayType` parameter which identifies which of the provided overlays should be displayed. This can be used to conditionally render different content based on the overlay type.

Custom parameters can be supplied to the overlay component via the `overlayComponentParams` grid option.

{% apiDocumentation source="grid-options/properties.json" section="overlays" names=["overlayComponent", "overlayComponentParams"] /%}

```{% frameworkTransform=true %}
const gridOptions = {
    overlayComponent: CustomOverlay,
    overlayComponentParams: {
        loadingMessage: 'Custom loading message',
        noRowsMessage: 'Custom no rows message'
    },
};
```

In the example below a single custom component is provided to the grid which contains the conditional logic about what to render for each `overlayType`. 

{% gridExampleRunner title="Overlay Component" name="custom-overlay-component"  exampleHeight=300 /%}

## Suppress Overlays

Each provided overlay can be suppressed via the `suppressOverlays` grid option which accepts an array of overlay types to suppress.

{% apiDocumentation source="grid-options/properties.json" section="overlays" names=["suppressOverlays"] /%}

## Legacy Customisation

Previously, the loading and no-rows overlays were customised via: `loadingOverlayComponent` and `noRowsOverlayComponent`. This approach is now superseded by the `overlayComponent` but the properties remain for backwards compatibility. The documentation for these properties is available [here](./overlays).



